Script2Video 取扱説明書

台本と収録音声から、音声・字幕・タイムラインを作り、画像・動画の素材と縦書きの吹き出し・ト書きを合成して、完成動画 output.mp4 を書き出すコマンドラインツールです。この説明書は v0.2.21(2026-11-08 時点)に合わせています。v0.2.1 で、台詞を最下段の横書きの字幕で出す字幕モード(字幕モード)を追加しました。v0.2.20 で、台本の #paragraph に style= を書いて、シーンごとに字幕と吹き出しを切り替えられるようにしました。v0.2.21 で、台詞行の style= で合成役の台詞だけスタイルを変えられるようにしました。

1. 概要と作業の流れ

すべてのコマンドは script2video <コマンド> <台本.txt> の形で使い、台本のあるフォルダ(以下「台本フォルダ」)を基準に読み書きします。1 本の動画は、次の順に作ります。

script2video number  第1話.txt
script2video build   第1話.txt [--voice-dir 収録/] [--config 設定.toml] [--no-cache]
script2video prompts 第1話.txt [--config 設定.toml]
script2video bubbles 第1話.txt [--config 設定.toml] [--port N] [--no-open]
script2video render  第1話.txt [--config 設定.toml]

2. インストールと前提

インストール(配布パッケージ)

Rust は不要です。宇摩コードワークスのサイトから Script2Video_v0.2.21.zip をダウンロードし、PATH の通ったフォルダに展開します。ffmpeg は同梱していないので、展開した install-ffmpeg.ps1 を PowerShell で実行して入れます。script2video --help で動作を確認します。

インストール(ソースからビルド)

# リポジトリの直下で実行。~/.cargo/bin/script2video.exe に入ります(PATH に ~/.cargo/bin が必要)
cargo install --path crates/s2v-cli --locked
script2video --help

コードを更新したら、同じコマンドをもう一度実行して入れ直します(同じ版でも入れ直すなら --force)。

前提

3. 台本フォルダの構成

台本フォルダ/
├─ 第1話.txt              台本
├─ 第1話.bak .ids .html   number の出力(バックアップ・番号の記録・閲覧用の台本)
├─ voices/                収録(S01_L001.wav …)。build は読むだけ
├─ full_dialogue.wav      build: 台詞・BGM・SE を合成した音声
├─ timeline/
│   ├─ timeline.json      build: 後のコマンドが読む正本(v3)
│   ├─ subtitles.srt      build: 字幕
│   └─ timeline.fcpxml    build: 動画編集ソフト(Filmora)向け
├─ tracks/                build: dialogue.wav / bgm.wav / se.wav
│                         あなたが置く: 画像・動画の素材(S01.png、S01_C02.mp4 …)
├─ prompts/               prompts: S01.md … と index.md
├─ bubbles.json           bubbles: 手動で置いた吹き出し・ト書き(.bak も)
├─ output.mp4             render: 完成動画
├─ output.stale.mp4       build が改名した前回の output.mp4
├─ work/                  中間ファイル(消してよい)
└─ Process.log            処理の記録・警告・エラー

• 台本のファイル名に、予約名(full_dialogue.wav・Process.log・output.mp4・output.stale.mp4・bubbles.json・bubbles.json.bak・.script2video.lock・prompts)は使えません(大文字小文字を区別しません)。
• work/・tracks/・timeline/・voices/・prompts/ をリンク(シンボリックリンク・ジャンクション)や台本フォルダの外にしないでください。どのコマンドも何も消さずに止まります。
• 同じ台本フォルダで 2 つのコマンドを同時に動かすと、後から始めた方が「別の script2video が実行中」で止まります(.script2video.lock による排他)。

4. 台本の書き方

詳しい規則は 台本仕様.md を参照してください。ここでは主な書き方をまとめます。

@scene 居間
朝の居間。明るく静かな雰囲気。
@pause
sentence 500
cast 300
paragraph 1000
@cast
田中:田中,pan=-25,distance=1.2
30代の男性。短髪で、紺のカーディガンを着ている。

佐藤:佐藤,pan=25,distance=1.2
20代の女性。肩までの黒髪。白いシャツ。

@script
#paragraph 朝の居間
#visual (image) 朝の光が差し込む居間。
#note 翌朝、居間。
田中:おはよう。今日は早いね。
佐藤:おはよう。コーヒー、淹れたよ。
#cut
#visual (video loop) カーテンが風に揺れる。
田中(volume=-0.2):ありがとう。いい香りだ。

セクション

台詞

[S01-L003] 役名(臨時パラメータ):台詞

• [S01-L003] は台詞 ID で、number が書き込みます。自分で書くときは省略できます。
• 役名と台詞の区切りは半角の : だけです(全角の : は区切りになりません)。
• 臨時パラメータは @cast の値への増減です(pan・distance・height・volume)。
• 合成役の台詞は (style=あまあま) で、その台詞だけスタイルを変えられます。指定できるのはその話者に含まれるスタイルだけで、ないスタイル・肉声役への指定・空の値はエラーです(話者に含まれるかは build の合成の前にエンジンの話者一覧で調べ、エラーの台詞は合成しません)。
• 合成役の台詞は (voice=rec) で肉声に切り替えられます。読み指定 '単語|読み' は合成役だけで使えます(表示は単語、エンジンへは読み)。区切りは最後の | なので、単語側に | を含められます('|||オアオア' は単語 ||、読み オアオア)。
• 台詞を重ねるときは overlap=ミリ秒(直前の台詞の終わりの何ミリ秒手前から)か、at=L003+500(指定の台詞の開始の何ミリ秒後から。別のシーンなら S01-L003)を書きます。

コマンド

カット・情景・ト書き

• カットは、その行の時点から、次の #cut かシーンの終わりまで続きます。カットごとに素材を 1 つ置きます(8. 素材の置き方)。
• #visual の印: image・video は素材の種類の希望(省略すると未指定)、loop は動画の素材がカットより短いときに繰り返す指定です。loop が無い動画は、最後のコマで止まります。
• ト書きは、その行の時点から、同じシーンの次の #note・次の #cut・シーンの終わりのうち、最も早いところまで表示します。
• 吹き出しは、台詞の音声が鳴っている間だけ表示します。位置と大きさは自動で決まり、bubbles で手動に直せます。config.toml で style = "subtitle" にする(台本の最初の style= より前のシーンの既定になる。以後の style= のないシーンは直前のシーンの方式を引き継ぐ)か、台本の #paragraph に style=subtitle を書くと、そのシーンの台詞は吹き出しではなく最下段の字幕になります(字幕モード)。字幕では 1 台詞が最大 3 行です。

5. number(番号付け)

script2video number 第1話.txt

台詞・シーン・カット・ト書きに番号を書き込みます([S01-L003]・#paragraph[S02]・#cut[C02]・#note[N01])。既存の番号は変えず、欠番も詰めません。台本名の .bak(書き換え前)・.ids(番号の記録)・.html(閲覧用)も出力します。

6. build(音声・字幕・タイムライン)

script2video build 第1話.txt
script2video build 第1話.txt --voice-dir 収録/     # 収録を別の場所に置いたとき

収録ファイル

• 台詞ごとに 1 ファイル、モノラルの wav を voices/ に置きます。ファイル名は台詞 ID の - を _ にしたもの(S01_L003.wav)。番号の桁数は問いません(S01_L3.wav も同じ台詞)。
• 台詞は自動で同じ音量(ラウドネス)にそろえます。

合成役の台詞

• @cast にエンジン名を書いた役の台詞は、build が音声合成して voices/S01_L003.wav に書きます(number は合成しません)。合成する台詞が無ければエンジンは起動しません。
• 文面や設定が変わっていなければ再合成しません。変わったとき、または別のファイル(肉声など)があるときは、既存のファイルを voices/backup/S01_L003.日時(UTC).wav に退避してから合成し直します。同じ台詞とみなされる別の名前のファイル(S01_L3.wav など)も、元の名前のまま日時を入れて退避します。退避すると警告になるので、その回の終了コードは 1 です。記録は voices/synth.json です。
• --no-cache では再合成しません。合成し直させたいときは voices/S01_L003.wav を削除します(削除したファイルは退避されません)。
• エンジンが使えない・合成に失敗した台詞は不足として仮の無音で配置し、終了コード 1 になります。
• --voice-dir を指定したときは、そのフォルダが無いと合成しません(省略時の voices/ は自動で作ります)。範囲ファイル(テイク)との組み合わせは未対応です。
• VOICEVOX / AivisSpeech の実行ファイルは、exe_path を省略すると、インストール先から自動で探します(VOICEVOX 0.26 以降の %APPDATA%\voicevox\vvpp-engines\… と、0.25 以前の Program Files\VOICEVOX\vv-engine など)。未起動のエンジンは build が起動し、終わると停止します。
• 使ったエンジンの接続先と実行ファイル(自動検出したパスを含む)、エンジンの探索・起動・停止の記録は、Process.log に残ります。

音量と定位

• 音量: 台詞ごとに同じラウドネスへそろえます([normalize] target_lufs、既定 -17.3)。番組の収録用に、基準距離(reference_dist = 1.0 m)の台詞のピークが -1 dBFS 前後になる値です。全体のピークは、マスターのソフトリミッタ([mix] master_ceiling_db、既定 -1.0 dBFS)で抑えます。ハードクリップは出ません。
• 声ごとのピーク差: ラウドネスをそろえても、声の質によってピークは数 dB 変わります。ピークをそろえたい役は、@cast の volume で調整します(例: ピークが低い役は volume=1.4)。Script2Voice の engine_volume_offsets(エンジン別の音量補正)に当たる設定はありません。
• 音量の確かめ方: full_dialogue.wav のピークは -1.0 dBFS 前後です。台詞ごとの値は timeline/timeline.json の measured_lufs・norm_gain_db で分かります。重ねた台詞(overlap=)の合計がマスターの上限を超える箇所は、ソフトリミッタが少し抑えます。
• 定位: pan(度。+ は右、- は左)は、ステレオのマイク(間隔 0.2 m)で拾った音として左右の音量差と時間差で表します。マイクは単一指向性([audio] mic_directivity = 0.5)で、左右のマイクを外側へ 30°(mic_angle = 30.0)向けた設定が既定です。±25° で左右の音量差が 2〜3 dB 程度です。もっとはっきりさせたいときは、pan を広げます(±60° など)。

出力

7. prompts(素材のプロンプトを作る)

script2video prompts 第1話.txt

timeline.json から、画像・動画を生成するためのプロンプトをカットごとに作り、prompts/ に書きます。

• prompts/S01.md …: シーンごとのファイル。カットごとに、作る素材のファイル名・種類・長さ(動画と種類未指定のとき)・プロンプト本文(コピーしやすいようコードブロック)を書きます。
• プロンプト本文の順: [prompts] style → シーン名 → #visual → 登場人物と外見 → [prompts] suffix。登場人物は、そのカットの間に話す人を台本の初出順に並べます。
• prompts/index.md: 全カットの表(カット・ファイル名・種類・長さ・素材の有無)。tracks/ の誤り(重複・種類違い・リンク)は末尾の「tracks/ の確認事項」に書きます。
• prompts/ の中で書き換え・削除するのは index.md と S<数字>.md だけです。自分のメモは別の名前(memo.md など)で置けます。

8. 素材の置き方

台本フォルダの tracks/ に、カットごとに 1 つ置きます。名前はカット ID から決まります。

• 拡張子: 画像は png・jpg・jpeg、動画は mp4・mov・webm(大文字小文字は区別しません。WebP は使えません)。
• 同じカットに 2 つ置く(拡張子違いを含む)、画像のカットに動画を置くなど種類が台本と違う、HDR や BT.2020 の色の動画は、render がエラーにします。
• 素材が足りないカットは、設定の [render] default_image があればその画像で代わりに書き出します(警告)。

9. bubbles(吹き出し・ト書きの配置を画面で調整する)

script2video bubbles 第1話.txt
script2video bubbles 第1話.txt --port 8765 --no-open

自動配置された吹き出し・ト書きを、ブラウザの画面で動かしたり、大きさ・尻尾・表示の時刻を直したりして、bubbles.json に保存します。render はこの配置を使います。調整しない項目は、毎回自動で配置されます。

• 字幕として描かれるシーン(style = "subtitle" の字幕モード、または台本の style=subtitle のシーン)の台詞は出さず、ト書きだけを出します。保存しても bubbles.json の台詞の手動配置は消さずに残します。bubbles 画面での文字サイズの設定は未対応です。
• 起動すると http://127.0.0.1:<ポート>/?token=… の 1 行を表示し、既定のブラウザで開きます(Windows)。開けなかったときや --no-open のときは、表示された URL を自分で開きます。
• --port を省くと、空いているポートを自動で選びます。
• 先に build を済ませておきます。ffmpeg・ffprobe とフォントの検査は render と同じです。

画面の構成

• 時刻はコマ番号で扱います。表示の出入りやカットの切り替えのコマは、render と同じ計算です。
• 動画の素材は、ループの指定があれば繰り返し、無ければ最後のコマで止まります(render と同じ)。
• ブラウザで再生できない動画の素材は、サーバーが ffmpeg でコマの画像にして見せます。

操作

保存と終了

• 保存されるのは手動で置いた項目だけです。保存のたびに直前の bubbles.json を bubbles.json.bak に残します。
• 「終了」は、未保存の変更があると確認を出します。タブを閉じるときも警告します。
• ターミナルで Ctrl+C を押すとすぐに終わり、未保存の変更は失われます。

10. render(動画を書き出す)

script2video render 第1話.txt

build の出力・tracks/ の素材・bubbles.json(あれば)から、吹き出し・ト書き・音声を合成して output.mp4(H.264 + AAC、既定 1920×1080・30fps)を書き出します。中間ファイルは work/render/ に作ります(消してよい)。

• 吹き出しとト書きは縦書きで描き、手動の配置が無い項目は自動で配置します。
• 自動の吹き出しが長すぎて画面に入らないときは、画面の大きさに切り詰めて警告します(終了コード 1)。手動の項目の文字が保存した枠に入らないときは、枠を広げて警告します。
• フォントに無い文字は、項目ごとに警告して代わりの字形で描きます。
• 字幕として描かれるシーン(style = "subtitle"、または台本の style=subtitle)では、台詞を縦書きの吹き出しでなく横書きの字幕で描きます(字幕モード)。台詞が四行以上になると、output.mp4 を作らずに終了コード 1 で止まります。
• 書き出した動画は、寸法・コマ数・音声の長さとずれを検査してから output.mp4 に置き換えます。失敗したときは前回の output.mp4 を変えません。

11. 設定(config.toml)

--config 設定.toml を省くと、同梱の config.toml を使います。全項目は同梱のファイルを参照してください。よく使うものは次のとおりです。

[render]

字幕モード(style = "subtitle")

config.toml の [render] で style = "subtitle" にすると、台本の最初の style= より前のシーン(と最初の #paragraph より前の台詞)の台詞を、render は画面の最下段に横書きの字幕で出します(この設定は最初の style= が現れるまでの既定で、台本の #paragraph の style= が優先し、以後の style= のないシーンは直前のシーンを引き継ぎます。コマンドラインのオプションはありません)。style = "bubble"(既定・省略時)の動作は従来と同じです。

• 字幕は台詞の音声が鳴っている間だけ表示します。幅は画面の幅から左右の margin を除いたもので、本文は最大 3 行です。折り返しは字幕の幅と font_size で決まります。
• 発言者名(@cast の役名)は、帯の上辺の左上に接する囲みのラベルで出します。行数には数えません。役名が空ならラベルは出ません。subtitle_show_speaker = false にすると、役名があってもラベルを出しません。
• 同じ時刻に複数の字幕が出るときは、下から上へ積み上げます。
• ト書きは字幕モードでも変わりません(縦書き・同じ枠・同じ自動配置)。字幕とト書きが時間も位置も重なると警告します(出力は作ります。終了コード 1)。帯が見える(塗りが透明でない、または枠線がある)ときは帯と発言者名の範囲で、帯が見えないときは画面に出る発言者名と文字の範囲で判定します。
• 文字の大きさは font_size で、吹き出し・ト書き・字幕で共通です。字幕だけの文字サイズの項目はありません。

台本の #paragraph の行の最後に style=bubble / style=subtitle を書くと、シーンごとに切り替えられます(例: #paragraph[S02] 港の朝 style=subtitle)。

• style= は行の最後の語だけが読まれます。名称の途中にあるものは名称の一部で、複数あれば最後の 1 つだけが指定になります。値は小文字の bubble / subtitle だけで、それ以外(空、Bubble など)はエラーです(build は終了コード 2 で止まります)。
• 省略したシーンは直前のシーンの方式を引き継ぎます。台本の最初の style= より前のシーン(と最初の #paragraph より前の台詞)は config.toml の [render] style に従います。元に戻すときは style=bubble と書きます。
• 字幕のシーンは上の字幕モードの規則(最大 3 行など)に従い、字幕の見た目の設定は全シーンで共通です。ト書きはどちらのシーンでも出ます。number は style= をそのまま残します。style= を書かない台本は従来と同じに動きます。
• bubbles 画面には字幕のシーンの台詞は出ません。保存しても、そのシーンの台詞の手動配置は消さずに残します。

[prompts]

[audio] / [normalize] / [mix]

[voicevox] / [aivis] / [xtts] / [http]

合成役を使うときだけ必要です(すべて省略可)。エンジンの接続先は url、未起動時に自動起動する実行ファイルは exe_path(引数は args、待機秒数は startup_timeout_s)で指定します。[http] の connect_timeout_s(既定 10)・request_timeout_s(既定 180)はエンジンへの通信のタイムアウトです。

12. 終了コードとログ

処理の記録・警告・エラーは、台本フォルダの Process.log に書きます。build・prompts・bubbles・render は、実行のたびに == build 2026-10-16 12:34:56(UTC) == のような区切り(日付と時刻。時刻は UTC)を付けて追記します。ログは上書きされないので、大きくなったら手で消してください。

合成役を使った build では、使ったエンジンの接続先と実行ファイルのパス(exe_path を省略したときは、自動検出したパス)、エンジンの探索・起動・接続確認・停止の記録も Process.log に残ります。エンジンの記録に警告があると、終了コードは 1 になります。

13. 困ったとき

14. 現在の制限と未確認の事項

開発者向けの設計は docs/superpowers/specs/、台本の詳しい規則は 台本仕様.md、コマンドの詳細は README.md を参照してください。